package com.bookmanagement.mapper;  // 声明当前接口属于com.bookmanagement.mapper包，遵循项目的分层结构（mapper层用于数据访问）

import com.bookmanagement.entity.Borrowing;  // 导入Borrowing实体类，该类对应借阅记录的数据模型，将作为方法的参数或返回值类型
import org.apache.ibatis.annotations.Mapper;  // 标记该接口为MyBatis的Mapper接口，Spring会自动扫描并通过动态代理生成实现类
import org.apache.ibatis.annotations.Param;  // 用于给方法参数指定名称，方便在XML映射文件中通过#{参数名}引用
import java.time.LocalDateTime;  // 导入Java 8的日期时间类，用于处理借阅Date（借阅时间）等时间字段
import java.util.List;  // 导入集合类，用于方法返回多条记录时使用（如查询多个借阅记录）
import java.util.Map;  // 导入Map类，用于返回统计类结果（以键值对形式存储数据，如月度借阅量统计）

@Mapper  // MyBatis注解：标识该接口是Mapper接口，MyBatis会为其创建动态代理实现类，无需手动编写实现
public interface BorrowingMapper {

    // 新增借阅记录
    // 参数：Borrowing对象（包含借阅相关信息）
    void insertBorrowing(Borrowing borrowing);

    // 根据ID查询单个借阅记录
    // 参数：Long类型的id（借阅记录唯一标识）
    // 返回值：匹配的Borrowing对象（若不存在则返回null）
    Borrowing findById(Long id);

    // 根据用户ID查询该用户的所有借阅记录
    // 参数：Long类型的userId（用户唯一标识）
    // 返回值：包含多个Borrowing对象的List集合
    List<Borrowing> findByUserId(Long userId);

    // 统计指定图书当前的有效借阅数量（可能用于判断是否可借阅）
    // 参数：Long类型的bookId（图书唯一标识）
    // 返回值：int类型的数量（有效借阅的记录数）
    int countActiveBorrowings(Long bookId);

    // 更新借阅记录信息（如归还时间、逾期状态等）
    // 参数：Borrowing对象（包含更新后的信息）
    void updateBorrowing(Borrowing borrowing);

    // 多条件分页查询借阅记录
    // @Param注解指定参数名，便于在XML中通过offset、pageSize等名称引用
    // 参数说明：
    // offset：分页偏移量（从第几条记录开始查询，用于分页）
    // pageSize：每页显示的记录数（分页大小）
    // borrowDate：按借阅日期筛选（可选条件，为null时不筛选）
    // bookTitle：按图书标题模糊筛选（可选条件）
    // username：按用户名模糊筛选（可选条件）
    // 返回值：符合条件的Borrowing对象集合
    List<Borrowing> findAllWithFilters(@Param("offset") int offset,
                                       @Param("pageSize") int pageSize,
                                       @Param("borrowDate") LocalDateTime borrowDate,
                                       @Param("bookTitle") String bookTitle,
                                       @Param("username") String username);

    // 统计符合多条件筛选的借阅记录总数（用于计算分页总页数）
    // 参数与findAllWithFilters一致（筛选条件）
    // 返回值：long类型的总记录数
    long countAllWithFilters(@Param("borrowDate") LocalDateTime borrowDate,
                             @Param("bookTitle") String bookTitle,
                             @Param("username") String username);

    // 查询所有逾期未归还的借阅记录
    // 返回值：逾期的Borrowing对象集合
    List<Borrowing> findOverdueBorrowings();

    /**
     * 按月统计借阅数量（统计分析用）
     * @return 月度统计结果集合，每个元素是Map：
     *         key为"month"时，value是String类型的"年-月"（如"2025-07"）；
     *         key为"count"时，value是Integer类型的该月借阅总数
     */
    List<Map<String, Object>> countBorrowingsByMonth();

    /**
     * 获取逾期费用与借阅时长的统计数据（统计分析用）
     * @return 统计结果集合，每个元素是Map：
     *         key为"duration"时，value是Integer类型的借阅天数；
     *         key为"overdueFee"时，value是BigDecimal类型的逾期费用
     */
    List<Map<String, Object>> getOverdueFeeStats();

    /**
     * 按班级和月份统计借阅数量（统计分析用）
     * @return 统计结果集合，每个元素是Map：
     *         key为"className"时，value是String类型的班级名称；
     *         key为"month"时，value是String类型的"年-月"；
     *         key为"count"时，value是Integer类型的该班级该月借阅总数
     */
    List<Map<String, Object>> countBorrowingsByClassAndMonth();

    /**
     * 根据ID删除借阅记录
     * @param id 借阅记录的唯一标识（Long类型）
     */
    void deleteBorrowing(@Param("id") Long id);
}